Document Timeout property behavior for RestClientOptions and RestRequest by Copilot · Pull Request #2331 · restsharp/RestSharp

Copilot · 2025-12-12T17:10:14Z

Description

Users were unclear about how RestSharp handles Timeout values of 0, -1, and other negative values. The documentation was minimal and still referenced the obsolete MaxTimeout property.

Purpose

This pull request is a:

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Changes

Source Code (XML Documentation)

Enhanced RestClientOptions.Timeout and RestRequest.Timeout with detailed remarks explaining:

Default: 100 seconds when not set
Infinite timeout: Timeout.InfiniteTimeSpan or TimeSpan.FromMilliseconds(-1)
Immediate cancellation: TimeSpan.Zero
Invalid values: Other negative values throw ArgumentOutOfRangeException

User Documentation

configuration.md updates:

Replaced obsolete MaxTimeout reference with Timeout
Fixed typo: TImeout → Timeout
Added "Configuring Timeouts" section with resolution priority, behavior table, and examples

Timeout Behavior Reference

Value	Behavior
`null`	Falls back to client timeout → default (100s)
Positive `TimeSpan`	Normal timeout after specified duration
`Timeout.InfiniteTimeSpan` / `TimeSpan.FromMilliseconds(-1)`	No timeout
`TimeSpan.Zero`	Immediate cancellation
Other negative values	`ArgumentOutOfRangeException`

Example

// Client-level timeout
var options = new RestClientOptions("https://api.example.com") {
    Timeout = TimeSpan.FromSeconds(30)
};

// Request-level override
var request = new RestRequest("resource") {
    Timeout = TimeSpan.FromSeconds(60)
};

// Infinite timeout
var longRequest = new RestRequest("long-operation") {
    Timeout = Timeout.InfiniteTimeSpan
};

Checklist

I have added tests that prove my fix is effective or that my feature works
I have added necessary documentation (if appropriate)

Original prompt

This section details on the original issue you should resolve

<issue_title>Documentation for RestClientOptions.Timeout and MaxTimeout</issue_title>
<issue_description>I know that MaxTimeout is obsolete and I should use Timeout instead, but I think this is similar to both.
I've seen that various programmers set RestClientOptions.MaxTimeout to zero or to minus one.
Is somewhere described, how RestSharp behaves in this two cases (0, -1)?
How does RestSharp behave when Timeout (I'm speaking about the new timespan) is negative?
I would like to see it somewhere described.
</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Documentation for RestClientOptions.Timeout and MaxTimeout #2328

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com>

cloudflare-workers-and-pages · 2025-12-12T17:16:20Z

Deploying restsharp with Cloudflare Pages

Latest commit:	`f84bd32`
Status:	✅ Deploy successful!
Preview URL:	https://465999c6.restsharp.pages.dev
Branch Preview URL:	https://copilot-add-documentation-fo.restsharp.pages.dev

View logs

Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com>

sonarqubecloud · 2026-02-26T12:52:38Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

github-actions · 2026-02-26T12:57:27Z

Test Results

42 files 42 suites 17m 26s ⏱️
503 tests 503 ✅ 0 💤 0 ❌
3 516 runs 3 516 ✅ 0 💤 0 ❌

Results for commit f84bd32.

qodo-free-for-open-source-projects · 2026-02-26T14:16:31Z

Review Summary by Qodo

Document Timeout property behavior and configuration guide
📝 Documentation

Walkthroughs

Description

• Enhanced XML documentation for Timeout properties in RestClientOptions and RestRequest
• Added comprehensive timeout behavior guide in configuration documentation
• Documented timeout resolution priority and supported timeout values
• Replaced obsolete MaxTimeout reference with Timeout and fixed typo

Diagram

flowchart LR
  A["Timeout Configuration"] --> B["XML Documentation"]
  A --> C["User Guide"]
  B --> B1["RestClientOptions.Timeout"]
  B --> B2["RestRequest.Timeout"]
  C --> C1["Timeout Resolution Priority"]
  C --> C2["Behavior Reference Table"]
  C --> C3["Code Examples"]
  C1 --> C1a["Request Level → Client Level → Default 100s"]
  C2 --> C2a["null, Positive, Infinite, Zero, Invalid"]

File Changes

1. src/RestSharp/Options/RestClientOptions.cs 📝 Documentation +10/-2

Document RestClientOptions.Timeout behavior

• Enhanced Timeout property XML documentation with default value (100 seconds)
• Added remarks section explaining infinite timeout, immediate cancellation, and invalid values
• Clarified that property is used when request timeout is not specified

src/RestSharp/Options/RestClientOptions.cs

2. src/RestSharp/Request/RestRequest.cs 📝 Documentation +9/-1

Document RestRequest.Timeout behavior

• Enhanced Timeout property XML documentation explaining override behavior
• Added remarks section with same timeout value behaviors as client options
• Clarified fallback to client-level timeout or default 100 seconds

src/RestSharp/Request/RestRequest.cs

3. docs/docs/advanced/configuration.md 📝 Documentation +49/-2

Add comprehensive timeout configuration documentation

• Replaced obsolete MaxTimeout with Timeout in client options table
• Fixed typo: TImeout → Timeout in request options table
• Added new "Configuring Timeouts" section with migration note from MaxTimeout
• Documented timeout resolution priority order and behavior table for all timeout values
• Provided practical code examples for client-level, request-level, and infinite timeouts

docs/docs/advanced/configuration.md

qodo-free-for-open-source-projects · 2026-02-26T14:16:32Z

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (0) 📎 Requirement gaps (1)

1. MaxTimeout 0/-1 undocumented 📎 Requirement gap ✓ Correctness

Description

The new timeout documentation mentions migration from MaxTimeout but does not document
MaxTimeout behavior for boundary values 0 and -1 as required. This leaves users without the
requested legacy guidance when migrating to Timeout.

Code

docs/docs/advanced/configuration.md[R236-238]

+:::note Migration from MaxTimeout
+In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
+:::

Evidence
PR Compliance ID 7 requires explicitly documenting MaxTimeout behavior for 0 and -1, plus
clarifying migration to Timeout. The added section references MaxTimeout migration but provides
no description of MaxTimeout=0 or MaxTimeout=-1, and the behavior table documents only Timeout
(TimeSpan?) values.
Document RestClientOptions.Timeout vs MaxTimeout behavior for 0, -1, and negative values
docs/docs/advanced/configuration.md[236-238]
docs/docs/advanced/configuration.md[249-257]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation adds a migration note for `MaxTimeout` but does not document what `MaxTimeout = 0` and `MaxTimeout = -1` do, which is explicitly required.

## Issue Context
Compliance requires explaining legacy `MaxTimeout` boundary behaviors (0 and -1) and clearly relating them to the newer `Timeout` (`TimeSpan?`) option.

## Fix Focus Areas
- docs/docs/advanced/configuration.md[232-258]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. MaxTimeout still documented 🐞 Bug ✓ Correctness

Description

The PR updates configuration docs to say MaxTimeout was replaced by Timeout, but other
non-versioned docs still show MaxTimeout usage and lists. Users following those examples will hit
compilation errors and conflicting guidance.

Code

docs/docs/advanced/configuration.md[R236-238]

+:::note Migration from MaxTimeout
+In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
+:::

Evidence

The new configuration docs explicitly document migration away from MaxTimeout, while another
current doc page still instructs users to set MaxTimeout and lists it as an option, which is
inconsistent with the documented API.

docs/docs/advanced/configuration.md[232-238]
docs/docs/usage/client.md[18-52]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Current (non-versioned) docs still reference `MaxTimeout` even though the PR documents that `MaxTimeout` has been replaced by `Timeout`. This leaves conflicting guidance and non-compilable examples.

### Issue Context
The PR improves timeout documentation in `advanced/configuration.md`, but other current docs pages need to match the same API surface.

### Fix Focus Areas
- docs/docs/usage/client.md[24-52]
- docs/docs/advanced/configuration.md[236-238]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. Timeout section breaks doc flow 🐞 Bug ✓ Correctness

Description

A sentence says the RestRequest configuration table is “below”, but the PR inserts a long
“Configuring Timeouts” section immediately after it, making the statement misleading and separating
it from the table it refers to.

Code

docs/docs/advanced/configuration.md[R232-234]

+## Configuring Timeouts
+
+RestSharp provides flexible timeout configuration at both the client and request levels. The timeout determines how long RestSharp will wait for a response before canceling the request.

Evidence

The document explicitly states the RestRequest table is below, but the newly added timeout section
starts immediately after, pushing the referenced table further down and disrupting the reading flow.

docs/docs/advanced/configuration.md[222-238]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The docs currently state that the RestRequest configuration table is “below”, but the newly added “Configuring Timeouts” section is inserted immediately after that sentence. This makes the statement misleading and disrupts navigation.

### Issue Context
This is a documentation-structure issue introduced by inserting a new section in-between an existing lead-in sentence and the content it references.

### Fix Focus Areas
- docs/docs/advanced/configuration.md[230-238]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

4. Timeout scope may mislead 🐞 Bug ⛯ Reliability

Description

The new docs imply the timeout applies to the whole request duration, but the implementation applies
the timeout token only to HttpClient.SendAsync; response reading/deserialization uses the caller
cancellation token only, so work after headers can exceed the configured timeout.

Code

docs/docs/advanced/configuration.md[R234-257]

+RestSharp provides flexible timeout configuration at both the client and request levels. The timeout determines how long RestSharp will wait for a response before canceling the request.
+
+:::note Migration from MaxTimeout
+In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
+:::
+
+### Timeout Resolution
+
+When making a request, RestSharp uses the following priority order to determine the timeout:
+1. `RestRequest.Timeout` (if set)
+2. `RestClientOptions.Timeout` (if set)
+3. Default timeout of 100 seconds
+
+### Timeout Values
+
+The `Timeout` property accepts a `TimeSpan?` value and supports the following behaviors:
+
+| Value | Behavior |
+|-------|----------|
+| `null` (not set) | Uses the next level timeout (client timeout, then default 100 seconds) |
+| Positive `TimeSpan` | Request times out after the specified duration (e.g., `TimeSpan.FromSeconds(30)`) |
+| `Timeout.InfiniteTimeSpan` or `TimeSpan.FromMilliseconds(-1)` | No timeout - request will wait indefinitely for a response |
+| `TimeSpan.Zero` | Request is canceled immediately (effectively no time allowed for the request) |
+| Other negative values | Throws `ArgumentOutOfRangeException` when the request is executed |

Evidence
Docs describe a general request timeout, but the code shows the timeout CTS is created and used for
SendAsync only. After that, ExecuteAsync passes the original cancellationToken (not the linked
timeout token) into response processing.
docs/docs/advanced/configuration.md[234-257]
src/RestSharp/RestClient.Async.cs[118-166]
src/RestSharp/RestClient.Async.cs[25-43]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Documentation currently reads like the timeout bounds the entire request duration. However, the implementation applies the timeout to `HttpClient.SendAsync` only, while response processing uses the caller token.

### Issue Context
This is especially relevant for large responses, streaming downloads, or slow deserialization where post-header work can outlive the configured timeout.

### Fix Focus Areas
- docs/docs/advanced/configuration.md[234-257]
- src/RestSharp/RestClient.Async.cs[26-36]
- src/RestSharp/RestClient.Async.cs[124-148]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

5. Negative timeout wording 🐞 Bug ✓ Correctness

Description

XML docs state negative values (except “-1 millisecond”) will throw ArgumentOutOfRangeException,
but RestSharp doesn’t validate; it passes the value directly into
CancellationTokenSource(TimeSpan). Consider wording this as underlying CTS validation (or add
explicit validation if you want it as a RestSharp contract).

Code

src/RestSharp/Options/RestClientOptions.cs[R190-194]

+    /// <list type="bullet">
+    /// <item><description>Set to <see cref="System.Threading.Timeout.InfiniteTimeSpan"/> (or <c>TimeSpan.FromMilliseconds(-1)</c>) for no timeout</description></item>
+    /// <item><description>Set to <see cref="TimeSpan.Zero"/> to cancel the request immediately</description></item>
+    /// <item><description>Negative values (other than -1 millisecond) will throw <see cref="ArgumentOutOfRangeException"/></description></item>
+    /// </list>

Evidence
The documented exception behavior is not enforced by RestSharp code; timeouts are directly provided
to CancellationTokenSource(...) without checks, so the throw behavior is an implementation detail
of the CTS constructor.
src/RestSharp/Options/RestClientOptions.cs[185-196]
src/RestSharp/RestClient.Async.cs[124-126]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Docs currently present negative-timeout validation as a RestSharp guarantee. In practice, RestSharp passes the value into `CancellationTokenSource(TimeSpan)` without validation.

### Issue Context
This is mostly a documentation-contract precision issue. Either the docs should explicitly attribute validation/exception behavior to CTS, or code should validate to make it an explicit RestSharp contract.

### Fix Focus Areas
- src/RestSharp/Options/RestClientOptions.cs[185-196]
- src/RestSharp/Request/RestRequest.cs[133-144]
- src/RestSharp/RestClient.Async.cs[124-126]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

ⓘ The new review experience is currently in Beta. Learn more

qodo-free-for-open-source-projects · 2026-02-26T14:21:31Z

docs/docs/advanced/configuration.md

+:::note Migration from MaxTimeout
+In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
+:::


1. maxtimeout 0/-1 undocumented 📎 Requirement gap ✓ Correctness

The new timeout documentation mentions migration from MaxTimeout but does not document MaxTimeout behavior for boundary values 0 and -1 as required. This leaves users without the requested legacy guidance when migrating to Timeout.

Agent Prompt

## Issue description The documentation adds a migration note for `MaxTimeout` but does not document what `MaxTimeout = 0` and `MaxTimeout = -1` do, which is explicitly required. ## Issue Context Compliance requires explaining legacy `MaxTimeout` boundary behaviors (0 and -1) and clearly relating them to the newer `Timeout` (`TimeSpan?`) option. ## Fix Focus Areas - docs/docs/advanced/configuration.md[232-258]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

qodo-free-for-open-source-projects · 2026-02-26T14:21:31Z

docs/docs/advanced/configuration.md

+:::note Migration from MaxTimeout
+In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
+:::


2. Maxtimeout still documented 🐞 Bug ✓ Correctness

The PR updates configuration docs to say MaxTimeout was replaced by Timeout, but other non-versioned docs still show MaxTimeout usage and lists. Users following those examples will hit compilation errors and conflicting guidance.

Agent Prompt

### Issue description Current (non-versioned) docs still reference `MaxTimeout` even though the PR documents that `MaxTimeout` has been replaced by `Timeout`. This leaves conflicting guidance and non-compilable examples. ### Issue Context The PR improves timeout documentation in `advanced/configuration.md`, but other current docs pages need to match the same API surface. ### Fix Focus Areas - docs/docs/usage/client.md[24-52] - docs/docs/advanced/configuration.md[236-238]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Initial plan

9b373a4

Copilot AI assigned Copilot and alexeyzimarev Dec 12, 2025

Copilot started work on behalf of alexeyzimarev December 12, 2025 17:10 View session

Document Timeout behavior for RestClientOptions and RestRequest

7968586

Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com>

Copilot AI and others added 2 commits December 12, 2025 17:18

Improve timeout documentation with dedicated section

3071c69

Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com>

Add migration note about MaxTimeout to Timeout property

23739fe

Co-authored-by: alexeyzimarev <2821205+alexeyzimarev@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add documentation for RestClientOptions.Timeout and MaxTimeout~~ Document Timeout property behavior for RestClientOptions and RestRequest Dec 12, 2025

Copilot AI requested a review from alexeyzimarev December 12, 2025 17:24

Copilot finished work on behalf of alexeyzimarev December 12, 2025 17:24

Merge branch 'dev' into copilot/add-documentation-for-timeouts

f84bd32

alexeyzimarev marked this pull request as ready for review February 26, 2026 14:16

alexeyzimarev merged commit 3831d52 into dev Feb 26, 2026
12 checks passed

alexeyzimarev deleted the copilot/add-documentation-for-timeouts branch February 26, 2026 14:16

qodo-free-for-open-source-projects bot reviewed Feb 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Document Timeout property behavior for RestClientOptions and RestRequest#2331

Document Timeout property behavior for RestClientOptions and RestRequest#2331
alexeyzimarev merged 5 commits intodevfrom
copilot/add-documentation-for-timeouts

Copilot AI commented Dec 12, 2025 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Dec 12, 2025 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Feb 26, 2026

Uh oh!

github-actions bot commented Feb 26, 2026

Uh oh!

Uh oh!

qodo-free-for-open-source-projects bot commented Feb 26, 2026

Uh oh!

qodo-free-for-open-source-projects bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

qodo-free-for-open-source-projects bot Feb 26, 2026

Uh oh!

qodo-free-for-open-source-projects bot Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Copilot AI commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Purpose

Changes

Source Code (XML Documentation)

User Documentation

Timeout Behavior Reference

Example

Checklist

Comments on the Issue (you are @copilot in this section)

Uh oh!

cloudflare-workers-and-pages bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying restsharp with Cloudflare Pages

Uh oh!

sonarqubecloud bot commented Feb 26, 2026

Quality Gate passed

Uh oh!

github-actions bot commented Feb 26, 2026

Test Results

Uh oh!

Uh oh!

qodo-free-for-open-source-projects bot commented Feb 26, 2026

Review Summary by Qodo

Walkthroughs

File Changes

Uh oh!

qodo-free-for-open-source-projects bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

qodo-free-for-open-source-projects bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

qodo-free-for-open-source-projects bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Dec 12, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Dec 12, 2025 •

edited

Loading

qodo-free-for-open-source-projects bot commented Feb 26, 2026 •

edited

Loading